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SESSION INITIATION PROTOCOL SERVLET 
APPUCATION PROGRAMMING INTERFACE 



Technical Field 



The present invention relates generally to telecommunications systems and more 
particularly to a Session Initiation Protocol servlet Application Programming Interface. 

Background oF the Invention 



The Session Initiation Protocol (SIP) is an application layer protocol for creating, 
modifying and terminating communication sessions among computing systems or other 
suitable devices, SIP is defined formally in Handley et al^ "SIP: Session Initiation 
Protocol " Internet Engineering Task Force, RFC 2543 (August 1999). Multiple 
15 participants may participate in each session. Examples of sessions include Internet 
multimedia conferences, Internet telephone calls and multimedia distribution sessions. 
The participants in a session may communicate via multicast, via a mesh of unicast 
relations or via a combination of multicast and unicast relations. 



20 Conventional systems do not provide a convenient mechanism for developing 

application programs that comply with SIP. A developer must custom develop 
applications and ensure that the applications confomi with the behavior mandated by SIP 
protocol. This difficulty makes application development cumbersome and discourages the 
proliferation of new applications that comply with SEP. Given the custom nature of such 

25 applications, maintenance of such applications may also be difficult. 

Summary of the Invention 



The present invention addresses the above-described limitations of conventional 
30 systems by facilitating the use of SIP servlets. The term "servlet," as used in this context, 
refers to a portion of computer codes that executes on a server to provide desired 
functionality. A servlet may be considered the server-side analog to an applet. In the 
present invention, the servlets provide telephone services logic. In one embodiment of the 
present invention, an Application Programming Interface (API) is defined for SIP servlets. 
35 An API is a set of methods that an application may use to request and cany out lower level 
services. The SIP servlet API identifies interfaces and objects that a servlet should support 
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to be a full fledged SIP servlet. The API identifies what functionality is needed for an SIP 
servlet. 

In accordance with one aspect of the present invention, an SIP servlet is provided in 
5 a data processing apparatus. The SIP servlet is run to implement telephone service logic. 
As part of the telephone services logic, the SIP servlet may examine, manipulate or redirect 
an SIP message, such as an SIP request or an SIP response. 

In accordance with another aspect of the present invention, scrvlcts are provided in 
10 a computing environment A servlet manager is provided for managing the servlcts. A 
conununication that complies with SIP is received. The servlet manager determines that a 
selected one of the scrvlets is to process the eonmiunieation, and the selected servlet then 
processes the conmiunication. 

1 5 In accordance with a further aspect of the present invention, an electronic device 

includes an interface for receiving an SIP message. The device also includes a servlet for 
handling the SEP message to implement telephone service logic, 

T^ricf Description of the Drawings 

20 

An illustrative embodiment of the present invention will be described below 
relative to the following drawings. 

FIGURE 1 depicts a block diagram of a first system that is suiuble for practicing 
25 the illustrative embodiment of the present invention. 

FIGURE 2 depicts a block diagram of a second system that is suitable for 
practicing the illustrative embodiment. 

30 FIGURE 3 is a flow chart illustrating the general steps performed to implement 

telephone services logic in the illustrative embodiment. 

FIGURE 4 is a flow chart illustrating the steps that are performed to implement call 
screening in the illustrative embodiment. 



2 
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FIGURE 5 is a flow chart illustrating the steps that are performed to implement call 
forwarding in the illustrative embodiment. 

5 Detailed Description of the Invention 

The illustrative embodiment sets forth an Application Programming Interface (API) 
for SEP servlets. Developers may use this API to develop SIP servlcts that provide 
customized behavior. The SIP servlets provide implementations of the methods set forth 

10 in the SIP servlet API* The SIP servlets enable users to dynamically extend the 

functionality of the server on the fly. The SIP servlets can inspect messages, change 
values of message headers, redirect messages and generally handle messages to implement 
telephone services logic For example, the SIP servlets can be used to implement call 
forwarding, call screening and mobility services. Those skilled in the art will appreciate 

15 the SIP servlets may also be used to implement additional telephone services logic. 

The SIP servlets of the illustrative embodiment may be vnrincn in a programming 
language, such as the Java programming language from Sun Microsystems, Inc. Those 
skilled in the art will appreciate that the servlets may also be written in other appropriate 
20 programming languages. 

SIP (i.e., sessions entail the passing of "calls") request messages and response 
messages. These are the two exclusive types of messages used in SIP. The response 
messages respond to request messages. For example, when a first user wishes to initiate a 
25 session with a second user, the first user sends an INVITE request to the second user. The 
second user receives the INVITE request and responds with a response message that 
identifies whether the second user wishes to participate in the session. 

Figure 1 depicts a block diagram of a first system 10 that is suitable for practicing 
30 the illusu-ative embodiment of the present invention. A user employs a user device 12 that 
is capable of communicating via SIP. The user device 12 may be a computer system, a 
cellular phone, an intelligent pager, a personal digital assistant (PDA) or more generally, 
any electronic device that is capable of participating in an SIP session. The second user 
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also employs a user device U, which may be any type of component that is capable of 
participating in an SIP session (such as listed above). 

In Figure 1, a SIP proxy service 16 is employed. The SIP proxy server 16 is an 
5 intermediary program that acts both as a server and client for the purpose of making 

requests on behalf of other clients. The SIP proxy server 16 may run on a dedicated server 
computer system or may be run on a shared computer system. Requests are either 
processed by the SIP proxy server 16 or passed on, after translation, to other servers. The 
SIP proxy server 16 interprets and. if necesisary, rewrites a request before forwarding the 
10 request A number of servlets 22 may be resident at the SIP proxy server 16 to implement 
telephone services logic. A servlet manager 20 is aUo resident at the SIP proxy server 16. 
" The servlet manager 20 is responsible for receiving messages and determining which of the 
servlets 22 arc to process the messages. 

15 The system 10 of Figure I also includes a user agent server 18. The user agent 

server 1 8 is a server appUcation that contacts the user of user device 14 when an SIP 
request is received. In addition, the user agent server 18 returns a response on behalf of the 
user of user device 14. A response accepts, rejects or redirects the request. The user agent 
server 18 may also have associated servlet manager 24 and servlets 26. 

20 ^ ^. 

Figure 2 shows an alternative system 28 for practicing the iUuslrative embodiment 

of the present invention. This system 28 includes user devices 30 and 32. System 28 

differs from system 10 in that system 28 employs a redirect server 34 rather than a proxy 

server 1 6. The redirect server 34 is a server that accepts an SIP request, maps the address 

25 set forth in the SIP request to a new address and returns this address to a client Unlike the 

SIP server 16, the redirect server 34 does not iniUate its own SIP requests and, in contrast 

to a user agent server 18, the redirect server 34 does not accept calls. The SIP redirect 

server 34 has an associated servlet manager 36 and servlets 38. 

30 Before discussing the details of the SIP servlet API provided by the illustrative 

embodiment, it is helpful to briefly review how the servlets may be employed. Figure 3 
provides a flow chart of an overview of the steps thai may be performed using the servlets. 
In general, a servlet is provided on one of the servers (step 40 in Figure 3). The servlet is 
run alone or in conjunction with other servlets to implement telephone services logic (step 
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42 in Figure 3). The telephone services logic may include any of a number of different 
types of call processing approaches that arc implemented in telephone systems. 

Figure 4 is a flow chart illustrating the steps that are performed to realize call 
5 screening. Initially, a server receives an INVITE request (i.e., an "invitation") for 

initiating a session (step 44 in Figure 4). The INVITE request contains caller information 
identifying tiie caller that wishes to initiate the session (i.c., the "call"). The caller 
information is noted by the servlet (step 46 in Figure 4). Based upon the caller 
information, the servlet determines whether to screen the call and how to screen the call 
10 (step 48 in Figure 4). The scivlct may access a database or other information source tiiat 
-identifies die appropriate way to screen the call. The information in the database, may, for 
example, inform the servlet that the call is to be blocked, redirected to an operator, directed 
to a voiccmail platform or placed in a queue. 

1 5 Figure 5 is a flow chart illustrating the steps that are performed to implement call 

forwarding. InitiaUy, a servlet receives an INVTTE request (step 50 in Figure 5). The 
servlet accesses a database or another information source to obtain call processing 
information. In this instance, the call processing information identifies that tiie call is to be 
forwarded. As such, the servlet notes that the caU has to be forwarded (step 52 in Figure 

20 5). The INVITE request is then forwarded to tiie appropriate destination (step 56 in Figure 

5). 

When a caller wishes to make an SIP call, tiie caller first locates a server and sends 
an SIP request to tiie server. The most common request is an INVITE request. The SIP 
25 request may be redirected or may trigger a train of new SEP requests by proxies. Users can 
register their locations with SIP servers. Users are located at hosts and arc identified by 
SIP URLs (Uniform Resource Locators). SIP URLs take tiie form of user@host, where tiie 
user part is a user name or telephone number and tiie host part is ciUicr a domain name or a 
numeric network address. 



30 



As mentioned above, each SIP message is either a request or a response. These 
messages use a generic message format as set fortii in RFC 822. D. Crocker. "Standard 
For The Format Of ARPA Internet Text Messages," Request For Comments 822, Internet 
Engineering Task Force, August 1982. The generic message format includes a start line, 
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one or more header fields, and an empty line thai indicates the end of the header fields and 
an optional message body. 

The illustrative embodiment defines an SipServlet abstract base object class that serves as 
5 the central abstraction of the SipServlet API. This abstract base class extends the 

GenericService object class» which implements the servlet interface. The SipServlet class 
defines the default method for handling all SIP requests. This method demultiplexes each 
request and is responsible for invoking the appropriate method on the proper instance of a 
servlet. The SipServlet abstract base class defines additional methods for handling 
1 0 particular types of SIP requests . These methods are automatically called by the service 
method (i.e,, the servlet manager) for processing an SIP request. Objects of the SipServlet 
object class support two packages: javax-servlet and servlet.sip. The javax. servlet package 
is a package that is defined by Sun Microsystems, Inc. of Palo Alto California. A 
"package" groups classes of objects by functionality. A "class" is a collection of data and 
1 5 methods that operate on the data. Each package groups a number of interfaces. An 
"interface" is akin to an abstract base class and provides a signature of methods and 
attributes that must be implemented by on object in order to support the interface. 

The servlct.sip package is defined as follows- 

20 

interface SipServletRequcst 
interface SipServletResponse 
interface SipSession 
interface SipBindingListener 

25 

class SipServlet 
class URI 

class SessionDescription 
class MediaDescription 
30 class SipUtils 

As can be seen above, the servlet.sip package includes four interfaces: the 
SipServletRequcst interface, the SipServletResponse interface, the SipSession interface 
and the SipBindingListener interface, rhcsc Interfaces will be described in more detail 
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10 



below. In addition. Ihc servlet.sip package specifics five object classes: the SipServlet 
object class, the URI object class, the ScssionDescription object class, the 
MediaDescription object class and the SipUtils object class. The SipServlet object class 
has beea described above. The URI object class is an object that encapsulates infonnation 
regarding SIP uniform resource identifiers. The ScssionDescription object class holds 
attributes and methods relating to particular sessions, and the MediaDescription object 
class holds attributes and methods relating to media that may be supported by serveir; 
during an SIP call. Lastly, the SipUtils object class is an object class that includes a 
number of utilities. 

- The SipServlctRequest interface is more formally defined as follows. 



public String gciAuihTypcO; 
1 5 public String getCallldQ; 

public long gctDatcHcader(String name); 
public String gctHeader(String name); 
public Enumeration gelHcadcrNamcsO; 
public int getlntHeader (String name); 
20 public String gctMethodQ; 

public String getPathlnfoQ; 
public String getPathTranslatedQ; 
public String gclQueryStringO; 
public Strijig getRemoteUserO; 
25 public String gctRequestedSessionlDO; 

public String getRequcsiURI(); 
public String getServletPathQ; 
public SipSession getSession (boolean create); 
public SipSession gctSessionQ. 
30 public boolean isRequestedSessionldValidO; 

Tlxe SipServlet Request interface defines an object to provide client request 
infonnation to a servlct. The gciAuthType method gets authcntification type informaUon 
from a request header. S IP supports a number of different authentication options. The 
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getCallld mclhod obtains the calUD from the request header. The calllD is a unique 
identifier of a call. The getDateHeader mclhod obtains a date header, field from a request. 
The gelHeader method obtains a header that is specified as a parameter to the mclhod. The 
gclHeaderNames method obtains names of the headers ai a given request. The 
5 getlntHeader method obtains an integer header. The gelMelhod mclhod obtains a method. 
The getPathlnfo method retrieves an SIP URI or other path information. The 
getPathTranslated method obtains parameters relating to path information for a path that 
has been translated. The getQueryString method obtains a query string, and the 
getRemoteUser method gets information regarding a remote user (i.e., the caller). The 
10 geiRequestedSessionlD method retrieves a session ID from a request. The getRcquestURI 
-obtains a request URI, and the getSeivletPath method retrieves a path to a servlet. The 
getSession method cither returns an existing session or retoms a value indicating that a 
session has not yet been created and creates a session. The isRequestedSessionldValid 
method remms a boolean value indicating whether a session ID is valid or not. 

15 

nie SipServletResponse interface extends the ServletResponse interface of the java 
x.servlet package. The SipServletResponse Interface is defined as follows. 



public static final int SC_TRYING; 
20 public static final int SCJRINGING; 

public static final int SC_CALL_BEGIN_FORWAJRDED; 
public sutic final int SC_CALL_QUEUED; 
public static final int SC_OK; 

pubUc static final int SC_MULTIPLE_CHOICES; 
25 public static final int SC_MOVED_PERMANENTLY; 

public static final int SC.MOVED_TEMPORAR1LY; 

public static final int SC_SEE_OTHER; 

public static fmal int SC_USE_PROXY; 

public static final int SC_ALTnRNATIVE_SERVICE; 

30 

public static final int SC_BAD_REQUEST; 
public static final int SC_UN AUTHORIZED; 
public static final im SC_PAYMENT_REQU1RED; 
public static final int SC_BAD_FORBIDDEN; 
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public static final int SC_NOT_F0UND; 
public static final int SC_METHOD_NOT_ALLOWED; 
public static final int SC_PROXY_AUTHENTICATION_REQUIRED; 
public static final int SC_REQUEST_TIMEOUT; 
5 public sutic final int SC^CONFLICT; 

public static final int SC_GONH; 
pubUc static final int SC_LENGTH_REQUIRED; 
pubUc static final int SC_REQUEST_URI_TOO_LARGE; 
public static final int SC_REQUEST_ENTITYjrOO_LONG; 
1 0 public static final int SC_UNSUPPORTED_MEDIA_TYPE; 

pubUc static final int SC_BAD_EXTENSION; 
public sutic final int SC_TEMPORAHLY_UNABAILABLE; 
.pubUc static final int SC_CALL_LEG_DNE; 
public static final int SC_LOOP_DBTECTED; 
1 5 pubUc static final int SC_TOO_MANY_HOPS; 

pubUc static final int SC_ADDRESS_INCOMPLETE; 
public static final int SC^AMBIGUOUS; 
pubUc static final int SC_BUSY_HERE; 
public static final int SC_SERVERJNTERNAL_ERROR; 
20 pubUc static final int SC_NOT_IMPLEMENTED; 

public static final int SC_BAD_GATEWAY; 
public static final inl SC_SERVICE_UNAVAILABLE; 
public static final int SC_GATEWAY_TIMEOUT; 
public static final int SC_VERSION_NOT_SUPPORTED; 
25 public static final int SC_BUSY_EVERYWHERE; 

public static final int SC_DECLINE; 
public static final int SC_D0ES_N0T_EXrr_A2*JYWHERE; 
public static final int SC_NOT_ACCEPTABI.E; 

30 public boolean containsHeader(String name); 

public void sendError(int sc, String mesg) throws lOException; 
public void sendErTor(int sc) throws lOException; 
public void sendRedircct(String location) throws lOException; 
public void setDatcHcadcr(String name, long date); 
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public void setHeaderCString name. String value); 
public void setlntHcadcr(String name, ini value); 
public void setStatus (int sc); 
public void selSiaius (int sc. String sm); 

As listed above, interface includes the defmition of a number of constants (i.e., 
static final variable). These constants correspond to the status codes defined within the SIP 
specification. 



The SipServletResponse interface also contains a number of methods. The 
containsHcader method returns a boolean value specifying whether the response contains a 
header or not Multiple sendError methods are defined to generate error alarms. The input 
parameters may include just a status code or may include a status code and a message in 
String format. The sendRcdirect mcdiod causes an exception to and specifies where a 
1 5 response is to be redirected. The setDateHeader method establishes a value for dale 
header, and the setHeader method establishes a value for a particular named header. The 
setlntHeader method sets a value for an integer header. The setStatus method sets a status 
code and may also include the additional parameter of a String that specifies a sutus 
message. 



20 



The SipSession interface contains the following methods. 



public long getCreationTimeQ; 
25 public String getld(); 

public long getLastAccesscdTimcO; 

public int getMaxInactivelntervalQ; 

public Object getValue (String name); 

public String [] getValueNamesQ; 
30 public void invalidatcQ; 

public boolean isNewQ; 

public void putValue(Siring name, Object value); 
public void TemoveValue(Siring name); 
public void setMaxinactivcltitcrval(int interval); 
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The gciCreationTime method returns the creation time for a session. The creation 
time information is retrieved from a session description object. The getid method returns a 
session ID. The gelLastAccessedTime method returns information regarding the last time 
5 a session was accessed. The gelMaxInactivelnterval method returns the largest period of 
lime for which the session has been inactive. The gctValue method returns a value for a 
given named attribute. The geiValuc names method rchims the names of values in a 
session description object. The invalidate method invalidates the session, and the isNew 
method returns a boolean value speci^g whether the session has been newly created or 
10 not. The putValue method establishes a value for a given attribute. The removeValue 

method removes a value, and the setMaxInactivelnterval method establishes a value for the 
maximum inactive interval attribute. 



15 



The SipScssionBindingListencr interfece is formally defined as follows. 

public void valueBound (SipSessionBindingEvent event); 
public void valueUnbound(SipSessionBindingEvent event. 

The SipSessionBindingListener interface extends the EventListener interface of the 
20 javax-servlet package. This interface primarily causes an object to be notified when it is 
bound or unbound from a session. 

As mentioned above, the servlet SIP package includes a number of objects. The 
SIP servlet object is more formally defined as follows. 

25 

public SipSetvlct 0; 

protected void doInvitc(SipScrvletRcquest req, SipScrvletResponse resp) 

throws ServletException, lOBxception; 
protected long getLaslModified(SipServletRequest req); 
30 protected void doAck(SipServletRequcst rcq, SipServlctRcsponse resp) 

throws ServletException, lOException; 
protected void doBye(SipServletRequest req, SipServletRcsonse resp) 

throws ServletException, lOException; 
protected void doCancel(SipScivlctRequcst req, SipServlctRcsponse resp) 
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throws ServlelException, lOException; 
protected void doRegister(SipServletRequest req, SipServletResponsc rcsp) 

throws ScrvletException, lOException; 
protected void doOptions(SipServleiRequest req, SipServletResponsc resp) 

throws ScrvletException, lOException; 
protected void service(SipServletRequest req, SipSeivletResponse resp) 

throws SexvlctException, lOException; 
public void service(ServletRequest req, ServletResponse resp) 

throws ScrvletException, lOException; 



10 



This object has a number of methods for handling respective types of requests. For 
example, the dolnvite method is used for handling INVTEE requests. Similar methods are 
also provided for the ACK, BYE, CANCEL, REGISTER and OPTIONS request. The 
service request provides a default service as has been described above. 

15 

The MediaDescription object is defined as follows: 
public class MediaDescription 

20 protected String name; 

protected String address; 

protected String title; 

protected String conncctionlnfo; 

protected String bandwidthlnfo; 
25 protected String encriptionKey; 

protected String duration; 

protected String mediaAttributes; 



30 



public MediaDescription Q; 

It contains the name, address and title attributes for the media. In addiUon, 
connection infomiauon and bandwidth infomiation is contained therein. An encriptionKey 
may be included in the media description object, and duration information specifying the 
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duration of information contained in the media may also be included. McdiaAttributcs 
nuy be contained therein. 

The SessionDescription object class is defined as follows. 

5 

public class SessionDescription 

protected String version; 
protected String owner; 
1 0 protected String name; 

' protected String sessionlnfo 
protected String URI; 
.protected String email; 
protected String phone; 
1 5 protected String cormectionlnfb; 

protected String bandwidthlnfo; 
protected Vector sessionAttrib; 
protected String duration; 
protected String schedule; 



20 



public ScssionDcscriptionO; 



The session description object holds description information regarding a particular 
session- The attributes include a version attribute, an owner attribute and a name attribute. 
25 The attributes may also conclude session information and a IJRT. Rmail information and 
phone information may also be stored as attributes. Connection information and 
bandwidth infonnation may be contained as attributes. Duration and schedule information 
may be contained as attributes and a vector of session attributes my also be contained 
therein. 



30 



Wliile the present invention has been described with reference to an illustrative 
embodiment thereof, those skilled in the art will appreciate that various changes in form 
and detail may be made without departing from the intended scope as defined in the 
attached claims. 
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Claims 

1 1 . In a data processing apparatus, a method, comprising the steps of: 

2 providing a Session Initiation Protocol (STP) servlet; aind 

3 running the SIP servlct to implement telephone service logic. 
4 

1 2. The method of claim I , wherein the data processing apparatus is an SIP server. 
2 

1 3. The method of claim 1 , wherein, as part of the telephone service logic, the SIP 

2 servlet examines an SD? message. 
3 

1 4. - Tlie method of claim 1, wherein, as part of the telephone service logic, the SIP 

2 ^'scrvleLprocesses an SIP invitation. 
3 

1 5, The method of claim I , wherein, as part of the telephone service logic, the STP 

2 servlet processes Sff requests. 
3 

1 6. The method of claim I, wherein, as part of the telephone service logic, the SIP 

2 servlet processes SIP responses. 
3 

1 7. The method of claim 1 , wherein the data processing apparatus is part of a network 

2 that supports the Internet Protocol (IP). 
3 

1 8. The method of claim 1, wherein tlie data processing apparatus is part of the 

2 Internet. 
3 

1 9. The method of claim 1, wherein the telephone service logic is call forwarding logic. 
2 

1 10. The method of claim 1 , wherein the telephone service logic is call screening logic. 
2 

1 11. In a computing environment, a method, comprising the steps of: 

2 providing servlets; 

3 providing a servlet manager for managing the scrvlcls 

14 
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receiving a communication that compUcs wiQi Oic Session Initiation 
Protocol (SIP); 

with the soviet manager, determining that a selected one of the servlets is to 
process the communication; and 

processmg the communication with the selected scrvlct. 

12. The method of claim 1 1, wherein the step of processing the communication 
comprises forwarding the communication to a destination. 

13. The method of clam 1 1 . wherein the step of processing the communication 
comprises modifying tlw communication. 

14. .Ihc metlxod of claim 1 1, wherein the step ofprocessing the communication 
comprises handling SIP requests. 

1 5. The method of claim 1 1 , wherein the step ofprocessing the communicaUon 
comprises handling SEP responses. 

1 6. A medium holding instructions for execution by a data processing apparatus to 

2 perform a method, comprising the steps of: 

3 providing a Session InitiaUon Protocol (SIP) scrvlct; and 

4 running the SIP scrvlet to implement telephone service logic. 

1 17. The medium ofclaim 16, wherein, as part ofthc telephone service logic, the SIP 

2 scrvlet examines an SIP message. 

3 

1 18. The medium ofclaim 16, wherein, as part of the telephone service logic, the SIP 

2 scrvlet processes SIP requests. 
3 

1 19. Tlie medium ofclaim 16. wherein the telephone service logic is call forwarding 

2 logic. 
3 

1 20. The medium of claim 16. wherein the telephone service logic is call screemng 

2 logic. 
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1 21. An electronic device, comprising: 

2 an interface for receiving a Session Initiation Protocol (SIP) message; and 

3 a scrvlet for handing the SIP message to implement telephone service logic. 

4 

I 22. The device of claim 21 , wherein the device is a computer system. 
2 

1 23. The device of claim 21 , further comprising additional servlets for providing 

2 additional telephone service logic. 
3 

1 24. The device of claim 21 , wherein the device receives additional SIP messages and 

2 wherein the device fiirthcr comprises additional servlets for processing the additional SIP 

3 -messages. 
4 

1 25. The device of claim 24, wherein the device further comprises oservlet manager for 

2 determining, for each of the additional SIP messages, which of the servlets is to process the 

3 message. 
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